<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang='en'>
  <head>
    <title>README.md</title>
    <meta content='text/html; charset=UTF-8' http-equiv='Content-Type'>
    <link href='../css/style.css' media='screen' rel='stylesheet' type='text/css'>
    <script type='text/javascript'>
      //<![CDATA[
        function popupCode(url) {
          window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
        }
        
        function toggleCode(id) {
          var code = document.getElementById(id)
        
          code.style.display = code.style.display != 'block' ? 'block' : 'none'
          return true
        }
        
        // Make codeblocks hidden by default
        document.writeln('<' + 'style type="text/css">.method .source pre { display: none }<\/style>')
      //]]>
    </script>
  </head>
  <body class='page'>
    <div class='file' id='wrapper'>
      <div class='header'>
        <h1 class='name'>README.md</h1>
        <div class='paths'>
          README.md
        </div>
        <div class='last-update'>
          Last Update:
          <span class='datetime'>2015-10-29 22:46:03 +0100</span>
        </div>
      </div>
      <div id='content'>
        <div id='text'>
          <div id='description'>
            
            <h1 id="label-kRPC-rb+rdoc-image-3Ahttps-3A-2F-2Fbadge.fury.io-2Frb-2Fkrpc.svg+rdoc-image-3Ahttps-3A-2F-2Ftravis-ci.org-2FTeWu-2Fkrpc-rb.svg-3Fbranch-3Dmaster">kRPC-rb <a target="_top" href="http://badge.fury.io/rb/krpc"><img src="https://badge.fury.io/rb/krpc.svg"></a> <a href="https://travis-ci.org/TeWu/krpc-rb"><img src="https://travis-ci.org/TeWu/krpc-rb.svg?branch=master"></a><span><a href="#label-kRPC-rb+rdoc-image-3Ahttps-3A-2F-2Fbadge.fury.io-2Frb-2Fkrpc.svg+rdoc-image-3Ahttps-3A-2F-2Ftravis-ci.org-2FTeWu-2Fkrpc-rb.svg-3Fbranch-3Dmaster">&para;</a> <a href="#top">&uarr;</a></span></h1>
            
            <p>kRPC-rb is a Ruby client library for <a
            href="http://forum.kerbalspaceprogram.com/threads/69313">kRPC</a>, a Kerbal
            Space Program mod that allows you to control KSP from external scripts
            running outside of the game.</p>
            
            <p><img
            src="http://drive.google.com/uc?export=view&id=0B2PFP23spNJwXzFCbmR0eDF5TVE"></p>
            
            <h2 id="label-Installation">Installation<span><a href="#label-Installation">&para;</a> <a href="#top">&uarr;</a></span></h2>
            
            <pre class="ruby"><span class="ruby-identifier">gem</span> <span class="ruby-identifier">install</span> <span class="ruby-identifier">krpc</span></pre>
            
            <h2 id="label-Basic+usage">Basic usage<span><a href="#label-Basic+usage">&para;</a> <a href="#top">&uarr;</a></span></h2>
            
            <pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;krpc&#39;</span>&#x000A;<span class="ruby-identifier">client</span> = <span class="ruby-constant">KRPC</span>.<span class="ruby-identifier">connect</span>(<span class="ruby-identifier">name</span><span class="ruby-operator">:</span> <span class="ruby-string">&quot;client name here&quot;</span>)&#x000A;<span class="ruby-identifier">vessel</span> = <span class="ruby-identifier">client</span>.<span class="ruby-identifier">space_center</span>.<span class="ruby-identifier">active_vessel</span>&#x000A;<span class="ruby-identifier">ctrl</span> = <span class="ruby-identifier">vessel</span>.<span class="ruby-identifier">control</span>&#x000A;<span class="ruby-identifier">ctrl</span>.<span class="ruby-identifier">sas</span> = <span class="ruby-keyword">true</span>&#x000A;<span class="ruby-identifier">ctrl</span>.<span class="ruby-identifier">sas_mode</span> = :<span class="ruby-identifier">stability_assist</span>&#x000A;<span class="ruby-identifier">ctrl</span>.<span class="ruby-identifier">throttle</span> = <span class="ruby-value">1</span>&#x000A;<span class="ruby-identifier">puts</span> <span class="ruby-node">&quot;Launching #{vessel.name}!&quot;</span>&#x000A;<span class="ruby-identifier">ctrl</span>.<span class="ruby-identifier">activate_next_stage</span>&#x000A;<span class="ruby-identifier">client</span>.<span class="ruby-identifier">close</span></pre>
            
            <p>Most of the API is <em>very</em> similar to what can be found in (official)
            Python client library. So official documentation at <a
            href="http://djungelorm.github.io/krpc/docs">djungelorm.github.io/krpc/docs</a>/
            is definitely a good read. The rest of this file describes few differences
            there are between Ruby and Python client libraries.</p>
            
            <h2 id="label-Connecting+and+disconnecting">Connecting and disconnecting<span><a href="#label-Connecting+and+disconnecting">&para;</a> <a href="#top">&uarr;</a></span></h2>
            
            <p>When you are in REPL, you can connect to kRPC server in this way:</p>
            
            <pre class="ruby"><span class="ruby-identifier">client</span> = <span class="ruby-constant">KRPC</span>.<span class="ruby-identifier">connect</span>(<span class="ruby-identifier">name</span><span class="ruby-operator">:</span> {<span class="ruby-identifier">name</span> <span class="ruby-keyword">for</span> <span class="ruby-identifier">the</span> <span class="ruby-identifier">client</span>}, <span class="ruby-identifier">host</span><span class="ruby-operator">:</span> {<span class="ruby-identifier">kRPC</span> <span class="ruby-identifier">server</span> <span class="ruby-identifier">host</span>}, <span class="ruby-identifier">rpc_port</span><span class="ruby-operator">:</span> {<span class="ruby-identifier">kRPC</span> <span class="ruby-identifier">server</span> <span class="ruby-identifier">rpc</span> <span class="ruby-identifier">port</span>}, <span class="ruby-identifier">stream_port</span><span class="ruby-operator">:</span> {<span class="ruby-identifier">kRPC</span> <span class="ruby-identifier">server</span> <span class="ruby-identifier">stream</span> <span class="ruby-identifier">port</span>})&#x000A;<span class="ruby-comment"># use client here...</span>&#x000A;<span class="ruby-identifier">client</span>.<span class="ruby-identifier">close</span></pre>
            
            <p>All of the <code>KRPC.connect</code>&#39;s arguments are optional, so
            <code>client = KRPC.connect</code> might be enough for you. Alternatively
            you can be more explicit (yet still obtain the same result):</p>
            
            <pre class="ruby"><span class="ruby-identifier">client</span> = <span class="ruby-constant">KRPC</span><span class="ruby-operator">::</span><span class="ruby-constant">Client</span>.<span class="ruby-identifier">new</span>( {<span class="ruby-constant">The</span> <span class="ruby-identifier">same</span> <span class="ruby-identifier">argument</span> <span class="ruby-identifier">list</span> <span class="ruby-identifier">as</span> <span class="ruby-constant">KRPC</span>.<span class="ruby-identifier">connect</span> <span class="ruby-identifier">has</span>} ).<span class="ruby-identifier">connect!</span>&#x000A;<span class="ruby-comment"># use client here...</span>&#x000A;<span class="ruby-identifier">client</span>.<span class="ruby-identifier">close</span></pre>
            
            <p>If you are writing a script, you can pass a block into
            <code>KRPC.connect</code>, <code>Client#connect</code> or
            <code>Client#connect!</code> methods. Connection to kRPC server is closed
            at the end of the block.</p>
            
            <pre class="ruby"><span class="ruby-constant">KRPC</span>.<span class="ruby-identifier">connect</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">client</span><span class="ruby-operator">|</span>&#x000A;<span class="ruby-comment"># do something with client here...</span>&#x000A;<span class="ruby-keyword">end</span> <span class="ruby-comment"># closes connection</span></pre>
            
            <h2 id="label-Data+structures+mapping">Data structures mapping<span><a href="#label-Data+structures+mapping">&para;</a> <a href="#top">&uarr;</a></span></h2>
            
            <p>kRPC server (and KSP itself) is written in C#. This means that during
            communication with the server there must be some data structure mapping
            being done. Most of the mappings are pretty obvious: numbers are mapped to
            <code>Float</code>s and <code>Integer</code>s, Strings to
            <code>String</code>s, Lists to <code>Array</code>s, Dictionaries to
            <code>Hash</code>es etc.</p>
            
            <p>It may be less obvious that Enum values are mapped to <code>Symbol</code>s:</p>
            
            <pre class="ruby"><span class="ruby-identifier">client</span>.<span class="ruby-identifier">space_center</span>.<span class="ruby-identifier">active_vessel</span>.<span class="ruby-identifier">situation</span> <span class="ruby-comment"># =&gt; :orbiting</span>&#x000A;<span class="ruby-identifier">client</span>.<span class="ruby-identifier">space_center</span>.<span class="ruby-identifier">active_vessel</span>.<span class="ruby-identifier">control</span>.<span class="ruby-identifier">sas_mode</span> = :<span class="ruby-identifier">prograde</span></pre>
            
            <p>To see all values for enum, you can call method that expects enum argument
            or returns enum value with <code>_doc</code> suffix. Alternatively you can
            print the hash that represents given enum:</p>
            
            <pre class="ruby"><span class="ruby-identifier">puts</span> <span class="ruby-constant">KRPC</span><span class="ruby-operator">::</span><span class="ruby-constant">Gen</span><span class="ruby-operator">::</span><span class="ruby-constant">SpaceCenter</span><span class="ruby-operator">::</span><span class="ruby-constant">SASMode</span> <span class="ruby-comment"># =&gt; {:stability_assist=&gt;0, :maneuver=&gt;1, :prograde=&gt;2, :retrograde=&gt;3, :normal=&gt;4, :anti_normal=&gt;5, :radial=&gt;6, :anti_radial=&gt;7, :target=&gt;8, :anti_target=&gt;9}</span></pre>
            
            <p>Tuples are mapped to <code>Array</code>s:</p>
            
            <pre class="ruby"><span class="ruby-identifier">client</span>.<span class="ruby-identifier">space_center</span>.<span class="ruby-identifier">active_vessel</span>.<span class="ruby-identifier">flight</span>.<span class="ruby-identifier">center_of_mass</span> <span class="ruby-comment"># =&gt; [-0.0015846538639403215, 0.0005474663704413168, 0.000849766220449432]</span></pre>
            
            <h2 id="label-Get+your+fingers+dirty">Get your fingers dirty<span><a href="#label-Get+your+fingers+dirty">&para;</a> <a href="#top">&uarr;</a></span></h2>
            
            <p>The best way to explore the API is to run REPL and try what each method
            does for yourself. I highly recommend using <a
            href="https://github.com/pry/pry">Pry</a> as REPL. This way you can
            <code>ls</code> any object you receive and see what methods you can call on
            it. When you want to know more about specific method, then just stuck
            <code>_doc</code> at the end of it&#39;s name and press enter:</p>
            
            <pre class="ruby">[<span class="ruby-value">29</span>] <span class="ruby-identifier">pry</span>(<span class="ruby-identifier">main</span>)<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">client</span>.<span class="ruby-identifier">space_center</span>.<span class="ruby-identifier">transform_position_doc</span>&#x000A;<span class="ruby-constant">SpaceCenter</span>.<span class="ruby-identifier">transform_position</span>(&#x000A;        <span class="ruby-identifier">position</span> :<span class="ruby-constant">Array</span>[<span class="ruby-constant">Float</span>, <span class="ruby-constant">Float</span>, <span class="ruby-constant">Float</span>], <span class="ruby-operator">-</span> <span class="ruby-constant">Position</span> <span class="ruby-identifier">vector</span> <span class="ruby-keyword">in</span> <span class="ruby-identifier">reference</span> <span class="ruby-identifier">frame</span> <span class="ruby-identifier">from</span>.&#x000A;        <span class="ruby-identifier">from</span> :<span class="ruby-constant">ReferenceFrame</span>, <span class="ruby-operator">-</span> <span class="ruby-constant">The</span> <span class="ruby-identifier">reference</span> <span class="ruby-identifier">frame</span> <span class="ruby-identifier">that</span> <span class="ruby-identifier">the</span> <span class="ruby-identifier">position</span> <span class="ruby-identifier">vector</span> <span class="ruby-identifier">is</span> <span class="ruby-keyword">in</span>.&#x000A;        <span class="ruby-identifier">to</span> :<span class="ruby-constant">ReferenceFrame</span> <span class="ruby-operator">-</span> <span class="ruby-constant">The</span> <span class="ruby-identifier">reference</span> <span class="ruby-identifier">frame</span> <span class="ruby-identifier">to</span> <span class="ruby-identifier">covert</span> <span class="ruby-identifier">the</span> <span class="ruby-identifier">position</span> <span class="ruby-identifier">vector</span> <span class="ruby-identifier">to</span>.&#x000A;) <span class="ruby-operator">:</span><span class="ruby-constant">Array</span>[<span class="ruby-constant">Float</span>, <span class="ruby-constant">Float</span>, <span class="ruby-constant">Float</span>] <span class="ruby-operator">-</span> <span class="ruby-constant">The</span> <span class="ruby-identifier">corresponding</span> <span class="ruby-identifier">position</span> <span class="ruby-identifier">vector</span> <span class="ruby-keyword">in</span> <span class="ruby-identifier">reference</span> <span class="ruby-identifier">frame</span> <span class="ruby-identifier">to</span>.&#x000A;&#x000A; <span class="ruby-constant">Converts</span> <span class="ruby-identifier">a</span> <span class="ruby-identifier">position</span> <span class="ruby-identifier">vector</span> <span class="ruby-identifier">from</span> <span class="ruby-identifier">one</span> <span class="ruby-identifier">reference</span> <span class="ruby-identifier">frame</span> <span class="ruby-identifier">to</span> <span class="ruby-identifier">another</span>. &#x000A;=<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">nil</span></pre>
            
            <p>I recommend ending the line with <code>;</code> to suppress printing return
            value (the <code>=&gt; nil</code> line at the end). If you want doc for
            method whose name ends with a <code>=</code> sign, you can put
            <code>_doc</code> before the <code>=</code>. Alternatively use
            <code>Object#send</code>, like in: <code>client.space_center.send&#x000A;&quot;active_vessel=_doc&quot;</code>.</p>
            
            <p>Combination of <code>ls</code>s and <code>_doc</code>s should teach you API
            in no time (also don&#39;t be surprised if you have a lot of fun with it
            too :))</p>
            
            <p><img
            src="http://drive.google.com/uc?export=view&id=0B2PFP23spNJwRWNIN3c2SWlpd0E"></p>
            
            <h2 id="label-Streaming">Streaming<span><a href="#label-Streaming">&para;</a> <a href="#top">&uarr;</a></span></h2>
            
            <p>A stream repeatedly executes a function on the server, with a fixed set of
            argument values. It provides a more efficient way of repeatedly getting the
            result of calling function on the server, without having to invoke it
            directly – which incurs communication overheads.</p>
            
            <p>To create a stream, call a method with <code>_stream</code> suffix. This
            will return <code>KRPC::Streaming::Stream</code> instance. You can call
            <code>get</code> (or <code>value</code>) on the <code>Stream</code>
            instance to get the recent value received by this stream. To deactivate the
            stream call <code>remove</code> (or <code>close</code>) on the
            <code>Stream</code> instance.</p>
            
            <p>Example without streaming: <code>ruby vessel =&#x000A;client.space_center.active_vessel refframe =&#x000A;vessel.orbit.body.reference_frame loop do   puts vessel.position(refframe)&#x000A;end </code> Equivalent example with streaming: <code>ruby vessel =&#x000A;client.space_center.active_vessel refframe =&#x000A;vessel.orbit.body.reference_frame pos_stream =&#x000A;vessel.position_stream(refframe) loop do   puts pos_stream.get end&#x000A;pos_stream.remove #note: dead code - just as an example </code></p>
            
            <h2 id="label-Want+to+know+more-3F">Want to know more?<span><a href="#label-Want+to+know+more-3F">&para;</a> <a href="#top">&uarr;</a></span></h2>
            <ul><li>
            <p>Read official <strong>kRPC documentation</strong> at <a
            href="http://djungelorm.github.io/krpc/docs">djungelorm.github.io/krpc/docs</a>,
            with many great <a
            href="http://djungelorm.github.io/krpc/docs/tutorials.html">tutorials and
            examples</a>.</p>
            </li><li>
            <p>Refer to <strong>kRPC-rb documentation</strong> at <a
            href="http://tewu.github.io/krpc-rb/doc">tewu.github.io/krpc-rb/doc</a></p>
            </li><li>
            <p>See official <strong>kRPC forum thread</strong> at <a
            href="http://forum.kerbalspaceprogram.com/threads/69313">forum.kerbalspaceprogram.com/threads/69313</a></p>
            </li></ul>
          </div>
          <div id='context'>
          </div>
        </div>
      </div>
      <div id='footer-push'></div>
    </div>
    <div id='footer'>
      <a target="docwin" href="http://github.com/mislav/hanna/tree/master"><strong>Hanna</strong> RDoc template</a>
    </div>
  </body>
</html>
